home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software Vault: The Gold Collection
/
Software Vault - The Gold Collection (American Databankers) (1993).ISO
/
cdr48
/
pavt117.zip
/
PAVT117.DOC
< prev
next >
Wrap
Text File
|
1993-04-24
|
22KB
|
496 lines
PAvatar 1.17
Turbo Pascal Avatar level 1 Console Kit
Copyright c 1991 Gregory P. Smith
Part I. Introduction
=======================================
This toolkit represents hundreds of hours of programming that
resulted in this fast and accurate product. PAvatar is a Turbo
Pascal unit (version 5.5 or later) that can provide your programs
with Avatar level 1 console, extended Avatar level 0+ (optional
ANSI fallback), ANSI-BBS, and ANSI terminal emulations. This is
done with a series of procedural hooks for screen I/O and cursor
control. This allows you to use the procedures of your choice,
making the unit the most flexible of its type.
An added bonus to using this unit is DESQview awareness.
This unit contains facilities for detecting DESQview, giving up
the time slice, and using DESQview's video buffer. This is
especially valuable for communications and bbs type programs that
are often run under DESQview.
Requirements
---------------------------
This unit requires that you are using an IBM compatible
computer and have Turbo Pascal 5.5 or later. As I have used OOP
for fast and efficient data management within this unit; I regret
that I cannot provide a Turbo Pascal 5.0 version of the PAvt1
unit.
Memory requirements within a program using PAvatar have been
kept to a minimum. Only 3-4k of heap space as well as less than
500 bytes stack space. The actual code itself only requires 16k.
Shareware
---------------------------
I am distributing this unit under a relaxed shareware concept
so as to promote Avatar. You are free to use the compiled unit
however you want, as long as I'm given credit for the terminal
emulations somewhere in the documentation or in the program
itself. Please let me know of any programs that you write using
PAvatar so that I can recommend them to others.
If you want the source code to this unit it is available for
$10 U.S., see the registration form for details. The possible
benefits of having source code are described later in this
document.
Liability
---------------------------
To use PAvatar you must first agree that I cannot be held
responsible for any damages or problems that occur from its use or
misuse. If you do not agree to these terms don't use this unit.
Part II. QUICK START
=======================================
First off you must install your unit. To do so, copy the
appropriate TPU file into your units directory (the TPU's have
been renamed to .T55 for TP 5.5 and .T60 for TP 6.0, you must
rename yours). Next, copy the demo program PAVTDEMO.PAS into your
pascal directory. Type TPC pavtdemo or compile it to disk from
the IDE. You now have a utility for displaying AVT/1, AVT/0+, and
ANSI files that is DESQview aware. Unless you're a Sysop, you
probably don't have lots of .AVT Avatar files. Currently there
are not many Avatar editors, but you may use my ANSI to Avatar/0+
converter to create Avatar files. It's found on BBS's as
A2AVTnnn.ZIP where nnn is the version number (currently 2.10).
When typing level 0 files, be sure to use the /PLUS parameter to
indicate that it is not a level 1 file (The differences are
described later).
Part III. Interface
=======================================
Procedures
---------------------------
PAvatar is a self sufficient unit in that only two procedures
are required to add an Avatar or ANSI terminal to your program.
However, there are more than two procedures available so that you
can take advantage of many special features of the unit. The
procedures and definitions follow.
Procedure Parse_AVT1 (ch:char);
This is the main procedure of the unit. It takes character ch
and parses it according to the status. For instance if you
pass it a ^V it would go into the Avatar command mode in which
the next character would represent an Avatar command. If it
were an Esc and ANSI was enabled, the next character passed to
it would be tested for a bracket '[' or a shorter VT52 style
ANSI commands. This is the heart of the whole unit.
Procedure ResetTerminal (nc,nl:byte);
This procedure is used to Reset the Terminal emulation with
screen dimensions nc columns and nl lines. It always takes
you back to the original mode with AVT/1 active, and ANSI
fallback turned off. It has the same effect as issuing a ^V^R
to the AVT/1 parser.
Procedure SetScreen(nc,nl:byte);
Use this procedure when you want to change the size of the
terminal screen without resetting everything else as in the
ResetTerminal procedure. The only thing this does is re-
define all of the Avatar windows to have nc columns and nl
lines.
Procedure AvtInterp (ch:char);
This procedure is called by the Parser to interpret the Avatar
codes after DLE's and special considerations have been
processed. When in ANSI_Only or AVT/0+ mode you can use this
instead of Parse_AVT1. The extra overhead of Parse_AVT1 is so
small that using this is usually not worth it.
Procedure AvtTTY (ch:char);
This procedure is called by the AVT/1 Parser when a character
is not part of a control code. It simply writes character ch
to the screen following the current Avatar window setup
(including flow, insert, direction, etc..). The only
characters that it processes are CR, LF, BS, Tab, and Bell.
You should not need this procedure, but it's here if you do.
Procedure Level0_Simulation (fallbck:boolean);
This procedure places the interpreter into an extended AVT/0+
emulation mode. If fallbck is true ANSI fallback will be on.
Internally, this procedure re-configures AVT/1's window 0 to
have a default color of cyan (3), as well as turning cooked
mode off. Using this procedure is more effective than sending
the equivalent codes for defining a level 0 simulation in a
certain window. Destructive backspaces are also disabled.
Procedure ANSI_Only;
Use this procedure when you want to place the parser in ANSI
Only mode. It is the equivalent of putting the AVT/1 parser
to sleep and disabling fallback. This is faster than fallback
mode.
Procedure AvtSound (note:byte; oct:shortint; dur:byte);
This procedure is a shortcut to stuff music into the Avatar
sound buffer without having to send the code to the parser.
Note represents the musical note in the same method which
AVT/1's ^V^S command uses it. That is note is equal to (tone
- 'A') * 2 + sharp where tone is somewhere between 'A' and
'G'. Sharp is a 0 or a 1 as the case may be. A pause is
generated by a note of 14 or greater. The octave is a signed
integer in oct where 0 represents middle octave and 1 the next
highest, -1 the next lowest. Dur is the duration in tenths of
a second. If two identical notes are queued in a row, they
will be played legato so that they run together.
Procedure StuffSound (frq,dur:integer);
This procedure is called by the above procedure. It is used
to place a sound of frq hertz and dur tenths of a second into
the Sound buffer. If the buffer is full, it will wait until
space is available.
Procedure Set_Sound_backg(backg:boolean);
All sounds produced by the PAvt unit, including the ^G bell,
will be made in the background if backg is set to true.
Otherwise they will be made in the foreground, delaying the
program until they finish. Sound defaults to the background
as that is the preferred method for AVT/1. It is worth noting
that with foreground sound the timer interrupt ($1c) is not
chained and/or DESQview sound calls are not made.
Function DESQview_version: word;
This is the first of the DESQview supportive routines in this
unit. The DESQview major version number is in the high byte,
while the minor version is in the low byte. A zero is
returned if DESQview is not loaded.
Procedure DV_Pause;
This procedure will give up the current time slice if you are
in DESQview. It does nothing otherwise. Use this procedure
when your program is not doing anything, to give the other
programs more processing time. Do not hesitate to use this
procedure, it's written in assembler so that it's execution
time isn't even measurable.
Function ReadKey: char;
This is a replacement for the Crt unit's ReadKey that gives up
the current DESQview time slice (via DV_Pause) if a key hasn't
been pressed.
Function In_Command: boolean;
Returns a true value if the interpreter is in the middle of
processing any Avatar or ANSI command. This is useful to
prevent strange displays or invalid commands when aborting
displays.
Procedure UpdateCursor(x,y:byte);
This procedure is used to update the cursor position within
the current Avatar window to x,y. If a 0 is passed for x, the
cursor will be reset to the correct position stored internally
by the parser.
Variables
---------------------------
There are only a few non-procedural variables that you can
use to check or modify the status of the terminal. They are all
static variables with defined defaults.
ANSI_BBS : boolean = False;
Use this variable to decide whether the ANSI portion of the
unit will use the "BBS" style. The only differences when this
is true are that Esc[2J also homes the cursor and Esc[J acts
the same as Esc[2J instead of Esc[0J. DOS's own ANSI.SYS is
infamous for processing Esc[2J this way.
Fallback : boolean = False;
This variable controls whether ANSI fallback will be on during
Avatar emulations. It is best not to mess with this variable
when using AVT/1 as it is designed primarily for use with
AVT/0+.
ScrnLines : byte = 25;
This variable simply defines the number of lines that you want
on your terminal screen. Modifying this variable can produce
strange results. It is recommended that you use the SetScreen
procedure to define the screen size.
ScrnColumns : byte = 80;
This variable is the partner of the above one. It defines the
number of columns you want on your terminal screen. The same
restrictions apply with this variable as on the above.
QueryReply : string[80] = 'AVT1, Avatar/1 Console Copr. 1991 Greg
Smith. Ver 1.17'+^M;
When the Avatar terminal id request is received this is the
string that will be returned. The "AVT1," at the beginning is
important to the remote terminal. It is used to define the
capabilities of the terminal. Everything else is just your
own logo or program ID. In level 0+ simulation mode the AVT1
is changed to AVT0.
Sound_Stat : byte = 3;
This variable is used to control which sounds are produced by
the unit. If bit 1 is set then the unit can make sounds. Bit
0 only controls the bell (^G) sound. As you can see, the
default is to have all sound enabled.
Dest_BS : boolean = True;
As the name implies, this variable controls the behavior of
the backspace (^H) character. The AVT/1 specifications
require a Destructive backspace while the AVT/0 specifications
require that it is non-destructive.
Constants
---------------------------
The following constants are available for general use.
Esc = ^[;
DLE = ^P;
FS = #28;
GS = #29;
RS = #30;
US = #31;
SP = #32; { space }
User Hooks
---------------------------
The interface for this unit has been designed to be as
flexible as possible without hindering the performance of the
unit. Besides the main procedures and a few variables most of it
is procedural hooks. Their definitions follow.
The Avatar interpreter does not check for invalid screen
coordinates on the hooks that need them. It is important that
your hooks check the integrity of the coordinates, otherwise
seemingly random lockups can occur when invalid or garbled
commands are processed.
Query_Hook : ReplyProc = Procedure (S:String);
This hook is used for all terminal queries or responses such
as the Avatar driver query and the ANSI report cursor
position. Usually these replies will be placed in the
keyboard buffer or sent out the comm port. In pavtdemo, the
hook is left at its null procedure setting as there is no use
for it in that type of utility. Note that information passed
to this hook should be inserted immediately into the input or
output buffer so that it is the next thing to be processed if
you wish to comply fully with the AVT/1 specifications.
WriteATh : WriteATHookT = Procedure (x,y,a:byte;ch:char);
This hook is simple and important. It should write character
ch on the screen at location x,y using attribute a. This is
the only thing it should do, it should not mess with the
cursor or scroll the screen. The coordinates are one based.
GotoXYh : GotoXYHookT = Procedure (x,y:byte);
This hook is used to set the cursor position. Often this
routine will call the Crt unit's GotoXY procedure. It is
provided for flexibility and the possibility of using PAvatar
in a virtual screen or window. Full checking against
ScrnLines and ScrnColumns is performed internally.
Scrollh : ScrollHookT = Procedure (dir,x1,y1,x2,y2,n,a:byte);
This hook is important to Avatar's power. It scrolls the
screen region of (x1,y1)-(x2,y2) n lines in the direction
indicated in dir (1=up, 2=down, 3=left, 4=right). The empty
area created by the scroll should be filled with blank spaces
of color attribute a. Most decent windowing toolkits have a
procedure suitable for this.
FillAreah : FillHookT = Procedure (x1,y1,x2,y2,a:byte;ch:char);
This hook is used to fill the screen region of (x1,y1)-(x2,y2)
with character ch in attribute a. If your scrolling procedure
doesn't support a fill color for the newly exposed area, this
is a good procedure to use for it.
GetATh : GetCharHookT = Procedure (x,y:byte;var a:byte;var c:char);
This hook is the opposite of the WriteATh hook in that its
purpose it to retrieve information from the screen. Variable
parameters c and a should be set to the character and
attribute at the coordinates of x,y respectively.
HighAreah : HighHookT = Procedure (x1,y1,x2,y2,a:byte);
Similar to FillAreah, this hook fills an area of the screen.
The area defined by (x1,y1)-(x2,y2) should be filled with
attribute a, but the characters on the screen should not be
modified.
Pauseh : PauseHookT = Procedure (tenths:word);
The only purpose of this hook is to allow for controlled
system pauses. This hook should pause the terminal for tenths
tenths of a second. The reason I didn't just use a delay(100)
within the unit is for the protection of the user. With
avatar, codes could be sent that could conceivable pause the
system for several days. It is up to you to add a method of
breaking out of a pause such as a key press.
FlushInputh : Procedure;
This hook has a default effect of zeroing the keyboard buffer.
If your program has any internal buffers or communications
buffer, you may wish to flush them when this hook is called.
The Avatar flush input command calls this hook.
The PAvt0 Small Version
---------------------------
Now included with the Pavt package is a PAvt0 Small version
of the unit. This unit is an AVT/0+ and ANSI-BBS terminal only.
It is much faster that the AVT/1 unit as there are no flow and
window controls. The primary use for this unit is for BBS door
programs which won't be using AVT/1. Overall the code there is
10.5k less code and 650 bytes less data as well as a minimal heap
usage. Compile the pavtdemo program with the compiler directive
of AVT0 for a demo of the PAvt0 unit.
The PAvt0 unit is designed as a drop in replacement for the
PAvt1 unit. However there are a few procedures and variables
which don't exist in the PAvt0 unit. The Pauseh and FlushInputh
hooks are not available, the Level0_Simulation, Parse_AVT1, and
Set_Sound_backg procedures are not available (AvtInterp should be
used instead of Parse_AVT1), and the ANSI_BBS variable is gone.
All of these were removed as they served no purpose in AVT/0+. In
addition, this unit parses tab characters (^I) as 8 spaces instead
of the definable (defaults to 8 char tabs) tab stops of the full
unit.
Part IV. Special Considerations
=======================================
Avatar 1 Console
---------------------------
The Avatar level one console is a very powerful terminal
emulation. Naturally it goes without saying that there are a few
things that must be considered if you wish to comply with the full
AVT/1 console specifications. I've already mentioned the need to
insert the query replies first into the input or output buffer.
Secondly, AVT/1 features a sleep mode for its interpreter, so ANSI
fallback should not be used (but it will work); a remote program
using level 1 codes should know how to switch between sleeping
(ANSI) and awake (AVT/1).
The main thing you should be concerned about in
communications is flow control. AVT/1 has a way to get around
interference with XON/XOFF flow control if the parser is in cooked
mode, but if it's switched to raw mode, the results may be
disastrous. As AVT/0+ is a raw only terminal, XON/XOFF must be
disabled while it is active.
Tips & Tricks
---------------------------
The AvtInterp procedure is actually a procedural variable
that is passed a character as its only parameter. This should let
you know a lot about how PAvatar works internally, as well as add
flexibility. If you wish to add your own terminal, just assign
your own procedures to AvtInterp. This will work when you are
calling AvtInterp directly instead of Parse_AVT1. Of course,
remember to call the parser when you switch to AVT/1.
If your program needs to execute a subprogram or shell to dos
there are some special precautions that you must take. You must
call the Set_Sound_backg() procedure to restore the timer
interrupt. You should also save the exitproc as Set_Sound_backg()
only restores it to it's very first state. Here is some sample
code for a dos shell:
SavedEP := ExitProc;
Set_Sound_backg(False);
SwapVectors;
Exec(GetEnv('COMSPEC''),'');
SwapVectors;
Set_Sound_backg(True);
ExitProc := SavedEP;
Part V. History And Credits
=======================================
I thank Ping Hansen in the FidoNet pascal echo and an unknown
someone in the FidoNet communications echo for sparking my
interest in terminal emulations and Avatar. I also would like to
thank G. Adam Stanislav for taking on the project of updating the
Avatar specification past its original Opus level commands. Last
but not least, I would like to thank my parents for putting up
with me being on the computer so many hours.
Release Sites
---------------------------
The following is a list of BBS's where you can find the
latest version of PAvatar as well as contacting me.
(303)779-4253 The Vault, 300-14400, Fido: 1:104/332
(303)674-1305 Wizardry line 1, 1200-9600. Fido: 1:104/630,631
(303)320-4078 CMOS BBS line 1, 300-9600, Fido: 1:104/441
(303)322-4125 CMOS BBS line 2, 300-9600, Fido: 1:104/469
(303)449-8946 Bohemia BBS Sys, 300-9600, (Unix System)
(303)750-7136 Borealis WildCat, 1200-9600, RIME: ->BOREALIS
Mark Cook, Sysop of Wizardry, is my only beta tester at this
time. I will acquire more as I feel the need. He has unconvered
most of the bugs hiding in PAvatar so far. Thanks Mark!
---------------------------------------------------------------------
Send all questions, comments, problems, ideas, money, etc.. to:
Gregory P. Smith
4422 Pali Way
Boulder, CO. 80301 USA
Fidonet: 1:104/332,441,477,630,631
RIME: ->BOREALIS
UseNet/InterNet: gpsmith@bohemia.metronet.org
CompuServe: Route to above internet address.